User's Choice Windows CD

home *** CD-ROM | disk | FTP | other *** search

/ User's Choice Windows CD / User's Choice Windows CD (CMS Software)(1993).iso / windows2 / hp22d1.zip / ADDEN2_2.DOC next >

Wrap

Text File | 1991-05-22 | 123KB | 4,237 lines

H Y P E R P A D Version 2.2 FILE: ADDEN2_2.DOC 20 May 1991 Addendum for Version 2.2 ~~~~~~~~~~~~~~~~~~~~~~~~ Copyright 1989-1991 by Brightbill-Roberts & Co. All rights reserved. ┌─────────┐ ┌─────┴───┐ │ (R) ──│ │o │────────────────── │ ┌─────┴╨──┐ │ Association of │ │ │─┘ Shareware └───│ o │ Professionals ──────│ ║ │──────────────────── └────╨────┘ MEMBER ┌──────────────────────────────────────────────────────────────────────────┐ │ Brightbill-Roberts & Co. │ Phone: (315) 474-3400 │ │ 421 University Building │ Fax: 472─1732 │ │ 120 East Washington Street │ BBS: 472─1058 │ │ Syracuse, NY 13202-4000 │ Compuserve: 75300,363 │ └──────────────────────────────────────────────────────────────────────────┘ This document supercedes and augments the information found in the HyperPAD User's Guide and Reference Guide. This addendum describes the changes and enhancements that were implemented in version 2.2 from the previous version (2.0) described in the main documentation. Table of Contents Getting Started ................................2 System Requirements ..........................2 Converting Pads to HyperPAD 2.2 File Format ..2 Installation .................................3 Microsoft Windows Support ......................6 New Command Line Parameters ....................8 Support for Read-Only Pads .....................13 Customizable Menus .............................14 Differences from HyperPAD 2.0 ................14 Quick Reference to Common Menu Commands ......15 New Object Types .............................17 New Commands .................................19 Menu Properties ..............................24 MenuItem Properties ..........................28 Menu Colors ..................................35 Menu Functions ...............................35 Handling System Menu Items ...................36 Multiple Separators ..........................36 doMenu Enhancements ..........................37 Menus with no visible items ..................38 Writing a "Window" Menu ......................38 Faster Language Execution ......................41 PADtalk Enhancements ...........................42 New or Enhanced Properties ...................42 New or Enhanced Messages .....................46 New or Enhanced Commands .....................47 New or Enhanced Functions ....................52 Enhanced Objects .............................56 Extension Enhancements .........................57 New Extension Callbacks ......................57 Sample Extensions ............................63 Support for TSR Programs .......................67 International Support ..........................68 Miscellaneous Enhancements .....................70 HyperPAD 2.2 Addendum This is a guide to the new features contained in HyperPAD 2.2. HyperPAD's major new features are concentrated in the following areas: o Customizable menus o Windows 3.0 support o Faster language interpreter Improvements have also been made in the following areas: o PADtalk - over 40 additions and improvements o Extensions - new callback functions o Read-only pads o TSR programs o International dates and times o Running under DesqView o Command line parameters o Miscellaneous features and fine tuning Where to go from here This guide is intended to be used as a supplement to the User's Guide and the PADtalk Reference Guide. Some information in this guide is highly technical and will only be used by advanced users. For first time users it is suggested that you read the section that follows called "Getting Started" and any other sections which may be of interest, then move on to the User's Guide. Advanced users, or users who have upgraded from version 2.0, should read this entire guide for a complete understanding of the new or enhanced features offered by HyperPAD 2.2. HyperPAD 2.2 Addendum 1 Getting Started System Requirements HyperPAD 2.2 will run on all IBM or compatible PCs with at least 390K of available memory. The Browser requires 328K of available memory. HyperPAD will run with ersion 2.1 or later (including DOS 5.0). A hard disk is required to install HyperPAD 2.2. Once installed, the necessary files can be copied onto floppy disks and run, although a hard disk is strongly recommended. Converting Pads to HyperPAD 2.2 File Format The file format for HyperPAD 2.2 pads is different from that of previous version of HyperPAD. Pads in the old format can be opened by HyperPAD 2.2 and run as normal. Once a pad has been opened and used by HyperPAD 2.2, there is no going back. You can use the PADINFO.EXE utility to determine the pad version (pads with version 7 are used by HyperPAD 2.2). The new file format is necessary due to the new instructions (pcodes) generated by the PADtalk compiler. These new pcodes are not understood by previous version of HyperPAD. 2 HyperPAD 2.2 Addendum Installation To install HyperPAD 2.2 onto your hard disk, use the installation procedure described on page 11 of the HyperPAD 2.0 User's Guide. The only difference between HyperPAD 2.2 and HyperPAD 2.0 is the number of disks (6 instead of 4) and the labels that appear on the disks. The procedure is outlined here for convenience: 1.Insert the disk labeled "Program Disk 1" into the A: drive. 2.Make that drive the current drive by typing: A: and pressing ENTER. 3.Type: INSTALL and press ENTER. Follow the instructions that appear on the screen, inserting the appropriate disks when asked. By default, HyperPAD 2.2 will be installed into a directory called \HPAD22 on your hard disk. The basic installation requires approximately 2.2 MB of disk space. If you choose to install the sample extensions, an additional 1.5 MB of disk space is required. Thus, for a full installation you need 3.7 MB of free disk space. HyperPAD's files are now stored in a compressed format. An uncompression program is used during the install process to expand the contents of the disks onto your hard disk. After copying the files, HyperPAD automatically executes in order to complete the installation of the pads. Once you exit HyperPAD, the installation files will be erased and the HPAD.INI file will be created. HyperPAD can also be installed from a directory, such as a directory on a network. To do this, copy all the files from the distribution disks into a single directory (on a hard disk or network), then run the install program. HyperPAD 2.2 Addendum 3 The HyperPAD install program sets up directories in the following manner: Directory Contains \HPAD22 HyperPAD files, utilities, and sample pads \HPAD22\TUTORIAL HyperPAD tutorial \HPAD22\EXTERN Sample extensions (optional) Installing HyperPAD for Microsoft Windows 3.0 There is a new PIF file for use when running HyperPAD 2.2 under Windows (HPAD.PIF). Further, there is an icon for use under Windows called HPAD.ICO. The procedure for adding HyperPAD 2.2 as a Windows program item is as follows: 1.At the Program Manager, select "New..." from the File menu. 2.Press ENTER to select "Program Item". 3.Type "HyperPAD 2.2" into the Description field. 4.Press TAB and type in the full DOS path of the PIF file, such as C:\HPAD22\HPAD.PIF". 5.Choose "Change Icon...". 6.Type in the full DOS path of the icon file, such as "C:\HPAD22\HPAD.ICO". 7.Select Ok to close the icon selection dialog box. 8.Select Ok. 4 HyperPAD 2.2 Addendum Installing HyperPAD for DesqView There is a new DVP file for HyperPAD (HP-PIF.DVP). This allows automatic installation of HyperPAD under DesqView. The procedure for adding HyperPAD to the DesqView menu is as follows: 1.At the main DesqView menu, press "O" to select "Open Window". 2.Type "AP" to add a program. 3.Press "O" to select Other. 4.Type in the directory containing the DVP file, such as "C:\HPAD22". 5.Use the arrow keys to move the highlight to the HyperPAD 2.2 item. 6.Press SPACE to select the item. 7.Press ENTER to add the program. 8.Press ENTER to select Done. HyperPAD 2.2 Addendum 5 Microsoft Windows Support HyperPAD now runs within the Windows 3.0 environment as a safe DOS application. Previous version of HyperPAD sometimes produced weird effects within Windows 3.0, such as excessive degradation in speed and even system crashes. Timer Change In order to become a safe application, HyperPAD 2.2 no longer revectors the system timer to perform timing functions (such as effect timing, dialing the phone, delays, and music). This method of timer usage was a major source of incompatibility in clone computers that caused HyperPAD to not work within Windows and DesqView. Instead of using the system clock (which HyperPAD would speed up to a millisecond rate) or the byte post mechanism supported by PS/2 BIOSs, HyperPAD now uses the interrupt 1Ch mechanism which is much safer. The old method of timer use, however, is still necessary to display effects and play music. For any of these operations, HyperPAD switches to the millisecond clock only for the duration of the music or the effect. Thus, when running under Windows, the play statement won't work and the effects run only at full speed. Automatic Detection Microsoft Windows is automatically detected using the semi- documented oldapp interrupt 2fh function calls. If present, HyperPAD makes the appropriate adjustments in the keyboard device driver for Windows to function properly. This method of Windows detection is only somewhat reliable. In such a case the auto- detection doesn't work, there is a new command line parameter that does the same thing. The /WINDOWS command line parameter This command line parameter (abbreviated /WIN) shuts off trapping of special keys sequences, some of which are used by Microsoft Windows and TSR software. 6 HyperPAD 2.2 Addendum The following table describes the conflicting keys and the alternate keys to use if running from within Windows. Key Used to: Alternative: ALT+ESC Switch between CTRL+Tool Letter browser and designer ALT+SPACE Toggle menu bar ALT+W,E on/off ALT+TAB Move the cursor CTRL+TAB (key between object number 58368 corners (using the when used Selector Tool) with the keyPress handler) ALT+SHIFT View solid portions no equivalent of the page CTRL+ALT Show all buttons and no equivalent fields using an outline SHIFT+SHIFT View the page without no equivalent the underlying background Miscellaneous Notes o The fxshow command will only run in Windows full screen mode. o When running HyperPAD within a window, the mouse will be inactive, as is the case with all DOS applications running within a window. The mouse cursor, however, remains on the screen. The following command removes the mouse from the screen: set the mouse to off; To restore the cursor, use the following command: set the mouse to on; HyperPAD 2.2 Addendum 7 New Command Line Parameters /NONOTIFY This parameter causes HyperPAD not display a message when you open a pad on a removable disk. hpad /nonotify /NORELOADMSG This parameter suppresses the message "Reloading HyperPAD, please wait..." when returning from running another program. hpad /noreloadmsg /WINDOWS This parameter forces HyperPAD to believe that Microsoft Windows is installed. The adjustments that HyperPAD makes when this parameter is given are described in the section titled "Microsoft Windows Support". hpad /windows /V This command line parameter causes HyperPAD to use video memory for its offscreen drawing, freeing up additional memory for your pads. When updating the screen, HyperPAD draws objects and paint to memory buffers, then copies this information to the real display. HyperPAD requires 3 such buffers at any one time (during certain effects, an additional offscreen buffer is required). The memory for these buffers is normally allocated from the system heap (somewhere below 640K). Using the /V parameter, however, causes HyperPAD to use the extra memory on the video card instead. All video cards have at least 12K of extra memory. The following table shows the memory savings depending on the video mode used: 8 HyperPAD 2.2 Addendum Video Mode Buffer size Memory savings 80x25 4000 bytes 12,000 bytes 80x43 6880 bytes 6880 bytes 80x50 8000 bytes 8000 bytes You should only use this parameter if you have a fast video card that doesn't have retrace (video "snow") problems. Using this parameter with a CGA card, for example, will slow down screen updates dramatically and cause constant annoying "snow". A 16 bit VGA, on the other hand, is fast and will function normally. /CARD, /MONITOR Due to the many differences in clone computers (e.g., BIOS bugs), HyperPAD's automatic detection of the video card and monitor type is not entirely reliable. The /CARD and /MONITOR command line parameters allow you to specify the exact video card and monitor type installed in your computer -- overriding HyperPAD's automatic sensing. An example where the use of these parameters is necessary is in PS/2 computers with both an 8514/A and VGA video adapters. HyperPAD cannot correctly recognize this configuration, and thus uses a weird color set (blue window shadows, etc...). Each switch is followed by a number corresponding to the value of that parameter. To set up HyperPAD for a VGA with a color display: hpad /card:8 /monitor:8 To set up HyperPAD for a monochrome display: hpad /card:0 /monitor:1 HyperPAD 2.2 Addendum 9 The monitor values are described in the following table: Monitor # Description 1 Monochrome Monitor 2 Glorified digital TV set 3 CGA Color Monitor 4 EGA Enhanced Color Monitor 5 Extended 400 line CGA monitor (on some laptops) 6 PGS HIRES Color 7 VGA Analog Monochrome 8 VGA Analog Color The card values are described in the following table: Card # Description 0 Monochrome 1 CGA 2 Extended CGA 3 Extended CGA - Plasma 4 Hercules Monochrome 5 EGA 6 Extended EGA 7 MCGA 8 VGA 9 Extended VGA 10 Leading Edge internal graphics adapter 10 HyperPAD 2.2 Addendum Other command line parameters The following table summarizes all of HyperPAD's command line parameters: Parameter Meaning NOMSG Don't read the HPAD.MSG file, saving approximately 4K of memory. Error messages and menu help text will not be displayed. 25 Creates new pads in 80x25 text mode. You can override this in the New... dialog box. 43 Creates new pads in 80x43 text mode (EGA and VGA only). You can override this in the New... dialog box. 50 Creates new pads in 80x50 text mode (VGA only). You can override this in the New... dialog box. NOSNOW Suppresses video snow checking, causing faster screen updating. NOMOUSE Suppresses use of the mouse. NOIDLE Disables sending of the idle message. This is handy for debugging pads with problems in their idle handlers. MONO Uses a monochrome color set. LCD Uses colors appropriate for LCD monitors (such as some laptops). B&W Uses a black and white color set. GREY Uses grey-scale colors. Use this option on the Compaq SLT. On the EGA and VGA, this actually translated colors to shades of grey. COLOR Uses a color set appropriate for color monitors. NOAUTOSAVE Disables automatic saving of the pad. This will increase the time required to write the pad when memory fills up. HyperPAD 2.2 Addendum 11 DEBUG Calls interrupt 3h after loading HyperPAD. This allows a resident debugger to be set up. NOKB Same as NO15. NO15 Disables use of interrupt 15h for HyperPAD's handling of the keyboard. Use this option on clone computers that exhibit weird keyboard behavior. ENHANCEDKB Forces HyperPAD to use an enhanced keyboard. Use this option if HyperPAD is not detecting your enhanced keyboard correctly. V Causes HyperPAD to use video memory for its offscreen drawing, saving about 12K of memory for 80x25 text modes and 8K for 80x43 or 80x50 text modes. Use this option only if you have a fast video card that doesn't have "snow" trouble. NORTC Don't use the real time clock for music and effects. This causes HyperPAD to speed up the system clock. NOEMM Don't use EMS memory if available. Use this option if you need to reserve EMS memory for TSR programs. NONOTIFY Don't display the "Removable disk..." warning on pads that are being run from a removable disk. WINDOWS Force HyperPAD into thinking that Microsoft Windows is running (abbreviated WIN). Freeing memory for use by Pads To run HyperPAD with the most memory free for your pads, use the following command line parameters: hpad /v /nomsg You can save additional space if EMS memory is installed and available. 12 HyperPAD 2.2 Addendum Support for Read-Only Pads When a pad is marked read-only, the pad file is physically opened in read-only mode, preventing any pad changes from being saved to disk. A new capability in version 2.2 lets you type into fields as normal, but when you change the page or go to another page, the modified page will revert to its original state. Some other notes concerning read-only pads: o You can now double-click on buttons and fields using the Selector tool. (A bug in earlier versions prevented objects in read-only pads from being double-clicked.) o You can select the Script... button from the Button Info dialog box or the Field Info dialog box without receiving an error. (A bug in earlier versions caused an extra error message to be displayed.) o Read-only devices such as CD-ROM and write-protected disks are automatically detected. A pad opened on disk media of this type will behave as if it has been marked read-only (even if it hasn't). o If a pad is marked read-only, the letter L (meaning "Locked") will appear on the status bar in column 77. HyperPAD 2.2 Addendum 13 Customizable Menus A major new feature of HyperPAD 2.2 is the ability to create and customize the menus. HyperPAD now provides full control over the appearance and behavior of the standard menus and full support for custom menus. The following list summarizes the new capabilities: o Add new menus to the menu bar. o Delete menus from the menu bar. o Add or delete menu items from any menu on the menu bar. o Delete menu items from existing menus, leaving some of the original menu items. The behavior of the original menu items (such as Copy being dimmed when unavailable) can be preserved as well. o Modify the appearance of a menu item, including dimming, checked, short-cut key, acceleratorKey, and help text. Differences from HyperPAD 2.0 Pads created with previous versions of HyperPAD are completely backward compatible with HyperPAD 2.2. Thus, doMenu handlers will work as expected. However, there are some minor visual differences. Because the menus are customizable, the diagrams in the User's Guide and the PADtalk Reference Guide that contain pictures of pull down menus no longer exactly match HyperPAD. Most notably, the names of the accelerator keys in HyperPAD 2.2 are completely spelled out (for example, ALT+F5 instead of *F5 and CTRL+F5 instead of ^F5). Another difference is in the size of the menus - - the menus in HyperPAD 2.2 are wider. Cut/Copy/Paste/Delete Modified The Cut, Copy, Paste, and Delete menu items no longer change their names according to the currently selected item. For example, Cut will no longer change to Cut Text, Cut Button, or Cut Field. For compatibility, the longer names are still supported through PADtalk. For example, the following commands perform the same function: 14 HyperPAD 2.2 Addendum doMenu "Cut"; doMenu "Cut Button"; doMenu "Cut Field"; doMenu "Cut Text"; doMenu "Cut Block"; Browser Differences The Browser has been significantly enhanced to support customizable menus. By default, the Browser has a menu bar with menu commands for each of the available functions. This menu bar can easily be removed (to simulate previous versions of the Browser) or enhanced in the same way as in HyperPAD 2.2. Quick Reference to Common Menu Commands To create a new menu: create menu "Commands"; create menu "Disk" after menu "File"; create menu "Features" before menu 5; To delete an existing menu: delete menu 1; delete menu "Edit"; To delete all of the menus: delete menus; To restore the menus to their HyperPAD default: restore menus; To add a menu item to an existing menu: put "My &Command" after menu "File"; put "Disk" after menuItem 2 of menu "Edit"; put "Features" before menuItem "Paint" of menu "Tools"; HyperPAD 2.2 Addendum 15 To check or uncheck a menu item: set the check of menuItem 1 of menu 1 to false; set the check of menuItem "Menu Bar" of menu "Workspace" to true; To enable or disable a menu item: set the dimmed of menuItem 1 of menu 1 to true; set the dimmed of menuItem 2 of menu "Workspace" to false; To temporarily hide a menu or menu item: set the visible of menu "File" to false; set the visible of menuItem "Copy" of menu "Edit" to false; To make a hidden menu or menu item visible: set the visible of menu "File" to true; show menu "File"; set the visible of menuItem 1 of menu 1 to true; show menuItem "Exit" of menu "File"; To change the help text of a particular menu or menu item: set the helpText of menu "File" to "Perform a file function."; put the helpText of menuItem 1 of menu 1 into the message box; To reference the number of menus or menu items: put the number of menus into the message box; put the number of menuItems of menu "File" into total; To see the names of all the menus: put the menus into the message box; 16 HyperPAD 2.2 Addendum New Object Types There are two new object types -- menu and menuItem. The menu object is used to refer to the name of the menu and the menu items within the menu. The menu object consists of many menuItem objects. The syntax used to reference these objects is as follows: menuRef -> menu [string | number] menuItemRef -> menuItem [string | number] of menuRef The following are sample menu and menuItem object references. menu "File" menu 1 menuItem "Open..." of menu "File" menuItem 1 of menu 2 The value of a menuItem consists of a semi-colon separated list containing the following: <menuName>;<isDimmed>;<isChecked>;<menuMsg>; <helpText>;<accelKey>;<isVisible> The following are sample menuItem values: "&Open...;FALSE;FALSE;;Open existing pad;F12;TRUE" "Run" "&Run A Program" "Open...";;;;Open an existing pad;;" HyperPAD 2.2 Addendum 17 The values of menu items can be used as shown in the following examples: put menuItem 1 of menu 1 into msg; set the delimiter to ";"; put true into item 2 of menuItem 1 of menu 1; Empty values in the semi-colon separated list of a menu item are given default values. For example, the statement put "Exit" into menuItem 1 of menu 2; assumes the following defaults: Item Default Value <isDimmed> false <isChecked> false <menuMsg> empty ("") <helpText> empty ("") <accelKey> empty ("") <isVisible> true The value of a menu object consists of a carriage-return separated list of zero or more menu items (one line for each menu item). The following is an example menu value: Re&cord...;FALSE,FALSE;;Records actions;;TRUE &Run...;FALSE;FALSE;;Executes commands;;FALSE &Edit...;TRUE;FALSE;;Edits a macro;ALT+E;TRUE Both menu and menuItem objects can be used as both source and destination references. For example: put "Disk" into menuItem 4 of menu "File"; put "Beep;FALSE;FALSE;;Make a noise;ALT+B;TRUE" into menu 3; set the delimiter to ";" if item 2 of menuItem 5 of menu "Edit" then answer "Paste is disabled!"; Numbering of Menu and MeneItem objects As described above, Menu and MenuItem objects can be referenced by number. Menus are numbered from 1 to the number of menus, 18 HyperPAD 2.2 Addendum starting on the left side of the menu bar. For example, the File menu is menu 1. If the File menu is not visible (i.e., the visible property is set to false), it is still referenced as menu number 1, even though Edit appears as the first menu on the menu bar. As another example, while using the Browse tool, the Block menu is not visible. This menu, however, can be referenced as menu number 8. The same is true for menuItem objects. Error messages Reference to a non-existent menu produces error 60, "Can't find menu." For example, you will receive this error message with the following command: put menu 66 into page field 1; Reference to a non-existent menu item produces error 61, "Can't find menu item.". For example, you will receive this error message with the following command: put menuItem 200 of menu 1 into the message box; New Commands The following commands have been added to facilitate creating and deleting menus and menu items: Command Description create Create a new menu delete Delete a menu, a menu item, or all the menus restore Restore a menu to the its default, or restores all menus HyperPAD 2.2 Addendum 19 create Syntax: create menu <menuName> [[before | after] <menuRef>; Purpose: This command creates a new menu after the last menu on the menu bar. Optionally, a menu can be created before or after any existing menu on the menu bar. Menus cannot be created which cause the total length of the menu bar to exceed the width of the screen (normally 80 characters). This command does not create menu items -- only a place holder on the menu bar with a name. Use the put command to add menu items to a menu after creating it. Examples: create menu "Commands"; create menu "Commands" after menu "File"; create menu "Commands" before menu 4; The following example moves the File menu to the end of the menu bar: put menu "File" into saved; delete menu "File"; create menu "File"; put saved into menu "File"; The next example creates a complete menu: create menu "Help"; put "&Index;FALSE;FALSE;;Index of help topics;;FALSE" into menu "Help"; put "&Keyboard;FALSE;FALSE;;Help on keyboard;;FALSE" after menu "Help"; put "-" after menu "Help"; put "About" after menu "Help"; 20 HyperPAD 2.2 Addendum delete Syntax delete menus; delete <menuItemRef>; delete <menuRef>; Purpose: This command deletes a menu, menu item, or all the menus, depending on the usage. After deleting a menu or menu item, the associated accelerator key will not work (such as PGUP, PGDN, ALT+F5, or F12). For example, deleting the Next command from the Go menu will also make PGDN inoperative. Note, however, that even though a standard menu command (such as those that appear on HyperPAD's default menus) is deleted, the doMenu message will still work from a script. For example, if the Next command is deleted from the Go menu, a script containing: doMenu "Next"; will still go to the next page. The syntax delete menus deletes all of the menus on the menu bar. Deleting all of the menus removes the menu bar, leaving only the status bar (if it's currently visible). Thus, the menu bar will only be displayed if there is at least one menu visible and the menu bar is currently on. Deleting a menu or menu item actually removes that menu or menu item from the menu bar. If you need to remove a menu or menu item temporarily, you can hide it by setting the visible property. Deleted menus and menu items of the standard HyperPAD menus can be recovered using the restore command. The Delete command behaves differently with menus and menu items than it does with containers (such as variables or fields). With containers, the delete command is equivalent to putting empty into the container. For example, the following two statements are equivalent: put empty into page field 1; delete page field 1; HyperPAD 2.2 Addendum 21 When deleting menus and menu items, the delete command actually removes the specified menu or menu item. If you want to create an empty menu or menu item, you must use the put command. For example, the following statement removes the File menu from the menu bar: delete menu "File"; -- remove the File menu The following command removes all of the menu items from the File menu: put empty into menu "File"; -- create an empty File menu The following command removes the first menu item from the File menu: -- remove the New command delete menuItem 1 from menu "File"; The following command creates an empty menu item: -- create empty item put empty into menuItem 1 of menu "File"; Examples: delete menus; -- delete all of the menus delete menu "File"; -- remove the File menu -- remove the Open... command delete menuItem 1 of menu "File"; delete the last menuItem of menu "Edit"; delete the first menuItem of the last menu; The following example removes a menu, then restores it: delete menu "Go"; : : restore menu "Go"; 22 HyperPAD 2.2 Addendum restore Syntax restore menus; restore <menuRef>; Purpose: The restore command is used to return a standard menu to its original state. The restore command can also be used to restore the menu bar to its default state, deleting all of the non-standard menus. The following menus can be restored individually: File Edit Database Go Tools Objects Workspace Block In the Browser, the following menus can be restored: File Edit Go Workspace The restore command is particularly useful for resetting the menus in order to edit a pad. For example, if the Tools menu has been deleted, you will be unable to switch tools. The following steps will restore the menus under such a circumstance: 1.Press ALT+F4 to place the cursor into the message box 2.Type restore menus and press ENTER Examples: restore menus; -- revert all menus to default state -- restore the File menu to original state restore menu "File"; restore menu 2; -- restores the menu at position 2 HyperPAD 2.2 Addendum 23 The following handlers modify the menu bar on entry to a pad, then restore it upon exiting. The handlers belong in a pad script. handler openPad; begin delete menus; -- delete all of the menus create menu "Commands"; put "Exit" into menu "Commands"; set the acceleratorKey of menu "Exit" to "ALT+X"; end; handler closePad; begin restore menus; end; Menu Properties The following list summarizes the properties of menu objects: Property Value Description name string Name of the menu, such as "File", that appears on the menu bar visible true or true if the menu is false visible, false otherwise helpText string Text that appears on the bottom line of the screen when the menu name is highlighted and before the menu has been pulled down dimmed true or Set to true to disable false all menu items, or false otherwise dimmed Purpose: The dimmed property is used to enable or disable all of the menu items of a particular menu. This property can only be set. The possible values are true and false. Be careful setting this property because of the double negatives. The following two statements help in determining which value to use: 24 HyperPAD 2.2 Addendum o Setting the dimmed to true disables all of the menu items. o Setting the dimmed to false enables all of the menu items. Examples: set the dimmed of menu "File" to true; set the dimmed of menu "Edit" to false; The following lines enable only the New... command on the File menu: set the dimmed of menu "File" to true; set the dimmed of menuItem "New..." of menu "File" to false; name Purpose: This property is used to get or set the name of a menu. Note that once the name of the menu has changed, the previous name can no longer be used as a reference to that menu. The first letter of the name of the menu is used as the accelerator key for that menu. For example, ALT+F is used as the accelerator key for the File menu. Always make sure that your menu names start with a unique letter, or you will have two menus with the same accelerator key. Any text can be used in the name of a menu. However, do not use carriage-returns, spaces, and other non-meaningful characters. Menu names with spaces may appear as two separate menus and confuse the user. Menu names can be any length as long as it fits on the menu bar. Examples: set the name of menu "File" to "Commands"; set the name of menu 1 to "Disk"; put the name of menu 3 into the message box; if the name of menu "1" is not "File" then answer "The menus have been modified." with "Ok"; HyperPAD 2.2 Addendum 25 visible Purpose: This property allows you to hide or show a menu. This is particularly useful if you need to hide a menu temporarily while the user is in a particular mode, then make the menu available later. The possible values are true and false. For example, suppose that you want a "Font" menu visible only when the user is within a particular field. You could show the menu (setting the visible to true) in the openField handler and hide the field in the closeField handler. The following two handlers within the script of a field will accomplish this task: handler openField; begin set the visible of menu "Font" to true; end; handler closeField; begin set the visible of menu "Font" to false; end; The visible property can be modified using the hide and show commands. Examples: if the visible of menu "Block" then answer "Using a paint tool."; -- hide the File menu set the visible of menu "File" to false; -- hide all the menus for i = the number of menus down to 1 do hide menu i; -- show the block menu (if it is hidden) show menu "Block"; Note: Modifying the visible property of a menu of menu item does not change its numbering. For example, if the file menu is not visible, it is still referenced as menu number 1. 26 HyperPAD 2.2 Addendum helpText Purpose: This property defines the text that appears on the status bar when the menu name is highlighted and the menu hasn't been pulled down. The maximum length is one character less than the width of the screen (normally 79 characters). Examples: set the helpText of menu "File" to "These are file commands."; put the helpText of menu 2 into page field 1; -- gather all of the help messages into a field: put empty into page field 1; for i = 1 to the number of menus do put the helpText of menu i after the last line of page field 1; -- to save memory, get rid of the help text... for i = 1 to the number of menus do set the helpText of menu i to empty; HyperPAD 2.2 Addendum 27 MenuItem Properties The menuItem object has the following properties: Property Value Description dimmed true or true if the menu false item is not selectable, false otherwise checked true or true if there is a false check mark next to the menu item, false otherwise menuMsg string Message to be sent when the menu item is selected acceleratorKey string Text that appears right justified in the menu helpText string Text that appears on the status bar. name string Name of the menu item, such as "Open...". visible true or true if the menu false item is visible on the menu, false otherwise The maximum allowable menu items in a menu is determined by the following formula: screenHeight() - 3 dimmed Purpose: This property is used to enable or disable a menu item. When true, the menu item is disabled. When false, the menu item is enabled. Setting the dimmed property of menu items is particularly useful for enabling choices depending on a mode that the user is in. For example, the Copy, Cut, and Delete choices are dimmed by HyperPAD when there is no selection. 28 HyperPAD 2.2 Addendum Disabled menu items cannot be selected. Further, the accelerator keys associated with a dimmed menu item will do nothing. HyperPAD disables and enables many standard menu items automatically, such as Cut, Copy, and Delete. Thus, if you modify the dimmed property of these menu items, they may not stay that way. (See the menuMsg property for more information.) Examples: set the dimmed of menuItem 1 of menu "Workspace" to false; -- don't allow new pads... set the dimmed of menuItem 1 of menu "File" to true; The following two handlers in the script of a listbox field enable a menu item only if the user has marked some lines: handler mark; begin get the markedLines of me is empty; set the dimmed of menuItem 3 of menu 4 to it; pass; end; handler unMark; begin get the markedLines of me is empty; set the dimmed of menuItem 3 of menu 4 to it; pass; end; checked Purpose: This property is used to place or remove a checkmark from a menu item. If true, a check mark (ASCII 251) is displayed to the left of the menu item. If false, there is no check mark. Menus that contain menu items with check marks are one character wider than normal menus. The check mark is useful as an indication that something in your pad is ON, enabled, or true. For example, the Message Box menu item in the Workspace menu is checked when the message box is currently open. HyperPAD 2.2 Addendum 29 Examples: set the checked of menuItem 1 of menu "File" to true; -- adjust the visibility of field depending on the state: set the visible of page field "Country" to the check of menuItem "International" of menu "MyMenu"; set the checked of the last menuItem of the last menu to false; menuMsg Purpose: The menuMsg property is used to send a message other than doMenu when a menu item is selected. You can use any one word identifier up to 32 characters in length -- i.e., any valid handler name. If the menuMsg property is empty, selecting a menu item will send a doMenu message. All standard menu items are sent as doMenu messages, the handlers for which are contained in HyperPAD itself. This allows you to intercept any menu command by simply defining a doMenu handler somewhere in the message path and passing only selected menu commands through to HyperPAD. If the menuMsg property is not empty, its value is sent as a message in place of the normal doMenu message. This allows you to define handlers for your own messages without having to intercept doMenu. The parameters sent along with this message are the menu item name, the menu name, and the menu item number. The following example shows how to declare such a handler: handler myMenus(ItemName,menuName,itemNumber); begin end; Setting the menuMsg property of a standard menu item has a special purpose in HyperPAD. Normally, standard menu items such as Cut, Copy, and Delete are dimmed automatically by HyperPAD depending on what is selected. If you want to redefine these menu commands for use in your own pads, this behavior is inacceptable (HyperPAD will override any dimming that you perform on these choices). To resolve this conflict, you can define the menuMsg of these items, causing HyperPAD to treat these menu items as user- defined rather than as standard. 30 HyperPAD 2.2 Addendum The following example changes these three menu items so that they can be used within a pad: set the menuMsg of menuItem "Copy" of menu "Edit" to "myEdit"; set the menuMsg of menuItem "Cut" of menu "Edit" to "myEdit"; set the menuMsg of menuItem "Delete" of menu "Edit" to "myEdit"; The following handler can now be used to define behavior for these menu items when they are selected. It operates on the contents of page field 1 and uses a global variable called "clipboard" in which to save the contents. handler myEdit(itemName,menuName,itemNumber,menuNum); begin global clipboard; if itemName is "Copy" or itemName is "Cut" then put page field 1 into clipboard; if itemName is "Cut" or itemName is "Delete" then delete page field 1; end; Examples: -- redefine the message sent by Cut: set the menuMsg of menuItem "Cut" of menu "Edit" to "myEdit"; -- set the behavior of Cut back to normal: set the menuMsg of menuItem "Cut" of menu "Edit" to "myEdit"; acceleratorKey Purpose: This property allows you to define an accelerator key for any menu item. The accelerator key name will appear right justified within the menu. Any text up to 32 characters can be used as the accelerator key. If the specified accelerator key name represents a valid key name, then that key will be used within HyperPAD to activate that menu item. Appendix 2 in the PADtalk Reference Guide lists all available key names. HyperPAD 2.2 Addendum 31 If the specified name is not a valid key name, the text will still appear in the menu. The key name is displayed right justified in the menu next to its corresponding menu item. When a menu is displayed, the width is determined by adding the width of the longest visible item name to the length of the longest accelerator key name plus 2 (plus 1 if any menu item is checked). Assigning an accelerator key redefines that key for all of HyperPAD. Pressing that key will send the menuMsg, if defined, or doMenu otherwise. Examples: set the acceleratorKey of menuItem 1 of menu 1 to "ALT+1"; set the accelKey of menuItem "Message Box" of menu "Workspace" to "ALT+M"; -- get rid of all accelerators: for i = 1 to the number of menus do begin for j=1 to the number of menuItems of menu i do set the accelKey of menuItem j of menu i to empty; end; Note: This property can be abbreviated accelKey. helpText Purpose: This property sets or gets the help text that appears on the status bar when the menu item is highlighted. Any text can be used, as long as the width is less than or equal to the screen width - 1 (normally 79 characters). Examples: set the helpText of menuItem 1 of menu "File" to "Create a new pad."; put the helpText of menuItem 3 of menu "Edit" into page field 1; 32 HyperPAD 2.2 Addendum name Purpose: This property gets or sets the name of a menu item. Any text can be used, including spaces, up to 40 characters in length. An ampersand (&) appearing before any characters makes that character the accelerator key for that menu item (such as 'x' in "E&xit"). The hyphen is used to make a separator bar (-). Examples: set the name of menuItem 1 of menu "File" to "&New..."; set the name of menuItem 2 of menu "File" to "-"; if the name of menuItem 3 of menu "Edit" is "Cut" then answer "Hello World" with "Ok"; The following example collects the menu item names into a popup menu: put the number of menuItems of menu "File" into numItems; put empty into list; for i = 1 to numItems do put the name of menuItem i of menu "File" after the last line of list; get popup(10,10,list); visible Purpose: This property hides or shows a menu item. The possible values are true and false. Hiding and showing menu items can be used to: o Implement long and short menus (hiding menu items in the short mode) o Remove menu items temporarily while a mode is set o Showing special menu items based on the user's privilege level o Disabling certain standard menu items to mask out capabilities for non-technical users. HyperPAD 2.2 Addendum 33 Hiding menu items is different than deleting in that the menu item can be unhidden at a later time in a single command. This is much faster than creating the menu item from scratch. HyperPAD itself uses hidden menu items to implement user levels. This capability is also used to hide and show tool specific menus (witness the Block menu which is only visible if using a paint tool). This property can also be modified using the hide and show commands. When modifying the visibility of menu items, it is possible to inadvertently create a strange looking menu, such as one that has two separator bars next to each other. HyperPAD relieves you from this complication by following these rules when displaying a menu: o Two separator bars in a row are collapsed into a single bar o A separator bar as the first visible menu item will not be displayed o A separator bar as the last visible menu item will not be displayed o Menus with no visible menu items will not pull down o Menus with only separator bars visible will not pull down The visibility of standard menu items is controlled by HyperPAD. For example, if you make the Paint Attr... menu item visible on the Workspace menu, HyperPAD will eventually correct this for you. Thus, you cannot count on standard menu items staying the way you like them (unless you change the menuMsg for that menu item). Examples: set the visible of menuItem 1 of menu 1 to false; hide menuItem 1 of menu 1; show menuItem 1 of menu "Workspace"; 34 HyperPAD 2.2 Addendum Menu Colors The colors of the menus are controlled with the menuColors property. This property returns a comma separated list of colors in the following format: <menu>,<dimmed>,<letter>,<hilite> The following table describes the colors values: Variable Description Default Value <menu> normal menu text. black on grey (112) <dimmed> dimmed menu items. dark grey on grey (120) <letter> short cut keys. red on grey (116) <hilite> highlighted menu grey on black (7) item and menu title. The following examples show how to change colors: -- default colors set the menuColors to 112,120,116,7; set the menuColors to green,grey,red,black on grey; put the menuColors into savedMenuColors; Note: Changing the menu colors also changes the color of the message box and the tool box. Menu Functions The following functions allow access to the number of menus and the number of menu items contained within a particular menu: the number of menus the number of menuItems of <menuRef> The menus() function returns a comma-separated list of the menu names. put the menus; if "File" is in the menus then doMenu "Open..."; HyperPAD 2.2 Addendum 35 The function may return a value such as: "File,Edit,Database,Go" Handling System Menu Items A system menu item is a standard menu item that HyperPAD dims, checks, and makes visible automatically. These menu items, when selected, generate a doMenu message with the menu item name as a parameter. If you set the menuMsg property for these menu items, HyperPAD will assume that you have redefined that menu item for your own application. For example, the following will redefine the New Page command on the Edit menu: set the menuMsg of menuItem "New Page" of menu "Edit" to "NewPageMsg"; If the value of the menuMsg property is empty, then HyperPAD will assume this is a system menu item. Note: A menu item is treated as a system menu item if the name of the menu item is the same as a standard menu item and there is no menuMsg defined for that menu item. Multiple Separators Invalid separator bars are ignored when drawing the menu. The following are invalid separator bars: o A separator bar as the first visible menu item in a menu o A separator bar as the last visible menu item in a menu o Two visible separator bars next to each other 36 HyperPAD 2.2 Addendum doMenu Enhancements The doMenu message now has additional parameters specifying the menu that initiated the message, the menu item number, and the menu number. The following declaration shows these parameters and the order in which they need to be declared: handler doMenu(itemName,menuName,itemNum,menuNum); begin end; Any doMenu handlers written for HyperPAD previous to version 2.2 will still work as normal. To make use of the new menu customization features, however, you will need access to the additional parameters passed with the doMenu message. For example: handler doMenu(itemName,menuName,itemNum,menuNum); begin if itemName is "Copy" then begin if menuName is "Edit" then answer "You picked standard Copy command" else answer "You picked Copy from the" && menuName && menu."; end else pass; end; The arguments to doMenu are described as follows: Argument to doMenu Description itemName The name of the menu item (such as "New...") menuName The name of the menu (such as "File") itemNumber The number of the menu item menuNumber The number of the menu HyperPAD 2.2 Addendum 37 The itemNumber and menuNumber parameters to doMenu are numbered from 1 to the number of items in the menu. Dimmed menu items count as a valid place holder. For example, if you have a menu with three menu items, the first two of which are dimmed, then the itemNumber of the third menu item is 3, even though the menu appears to have only one menu item. Menus with no visible items If a menu has no visible items, there will be no corresponding pulldown menu. However, the menu names on the menu bar can still be selected. Selecting a menu name issues a doMenu message with the following parameters: itemName: Name of the item menuName: Name of the menu itemNumber: Item number (equal to 0) menuNumber: Menu number Writing a "Window" Menu The following PADtalk handlers implement a Windows-style "Window" menu that contains a list of the pads that have been accessed most recently. Selecting one of items from the Window menu will take you immediately to that pad. 38 HyperPAD 2.2 Addendum The following handlers belong in the pad script of the Home pad: -- this handler gets control when an item is selected handler gotoPad(itemName,menuName,itemNumber); begin go to pad itemName; end; handler quit; begin global menuData; -- put the file in the same place as HPAD.EXE get findFile("HPAD.EXE"); set the delimiter to "\"; put "MENUS.DAT" into the last item of it; set the delimiter to ","; -- create the file and put the menu data into it put create(it) into fh; write menuData to fh; close fh; pass; end; -- this handler adds the pad named 'padName' to the Window menu handler addPadToMenu(padName); begin global menuData; if padName is in menuData then exit; put padName & ";FALSE;FALSE;gotoPad;Go to this pad.;;TRUE" after the last line of menuData; end; HyperPAD 2.2 Addendum 39 handler startup; begin global menuData; -- find the menu data file, if a previous one is around get findFile("MENUS.DAT"); if it & "X" is not "X" then begin put open(it) into fh; read from fh until end; close fh; end; put it into menuData; addPadToMenu the longName of this pad; -- create the Window menu with the data from the file create menu "Window"; put menuData into menu "Window"; end; handler openPad; begin global menuData; -- Create the menu, if it isn't already there somewhere if "Window" is not in the menus then create menu "Window"; addPadToMenu the longName of this pad; put menuData into menu "Window"; end; handler resume; begin startup; pass; end; 40 HyperPAD 2.2 Addendum Faster Language Execution The pcode interpreter built in to HyperPAD has been significantly optimized for speed and code size. The following table summarizes the improvements: Functional Area Implications Looping Loops involving counting variables are faster Internal data Assignments using the put conversions command are faster Internal WORD Significantly speeds up data type arithmetic involving integers (number without fractional portions) Message passing Messages get passed through the hierarchy faster pcode Script code is smaller and collapsing faster Numeric Comparing numbers in a boolean comparisons expression is faster HyperPAD 2.2 Addendum 41 PADtalk Enhancements New or Enhanced Properties brackets This property modifies the characters used to hold the check mark with check box buttons. The possible values are true and false; the default is true. Setting the brackets to true makes a button looks like this: [ ] New Button Setting the brackets to false makes a button look like this: ( ) New Button Parenthesis are used within option button groups (radio buttons) to distinguish them from regular option buttons. The following examples show how to change this property: set the brackets of page button 1 to false; set the brackets of button "Portrait" to true; delimiter This property changes the item delimiter (which is usually a comma) to another character: set the delimiter to "\"; set the delimiter to "|"; The delimiter can be set to any character from ASCII 1 to ASCII 255. The following example saves the delimiter, changes it , then sets it back later: put the delimiter into savedDelimiter; set the delimiter to "#"; put item 2 of "hello#there#person#wow" into the message box; set the delimiter to savedDelimiter; 42 HyperPAD 2.2 Addendum Note: The delimiter is set back to its default value (a comma) during idle time (at the end of all pending handlers). edgeType The range of field edge types is from 0 through 15. Edge type 0 creates a field with a transparent edge. Thus, by setting the edgeType to 0, you can create a field with only a scroll bar visible. For example: -- no edge - keep scrollbar set the edgeType of page field 1 to 0; set the withEdge of page field 1 to true; focus The focus property can now be used to set the focus to objects while using the selector tool. This is especially useful for copying and pasting objects between pads. The following handler in a button script copies itself, then deletes itself, then pastes the copy of itself on another page. handler select; begin doMenu "selector"; -- use the Selector tool set the focus to me; -- select this button doMenu "Cut"; -- cut the button go to the next page; -- change pages doMenu "Paste"; -- paste it here doMenu "Browse"; -- go back to the Browse tool end; homePad The homePad property allows you to set the pad used as the Home pad. By default, the homePad property is set to HOME.PAD. If HyperPAD was unable to locate the home pad on startup, the value of homePad will be empty (""). You can set the homePad property to any valid pad. The new pad will replace the current home pad with the new one, re-routing all messages through the new pad (in effect, replacing the home pad in the message path). HyperPAD 2.2 Addendum 43 Examples: -- change the Home pad to the Phone pad... set the homePad to "phone"; -- get rid of the Home pad from the hierarchy.. set the homePad to empty; -- set the home pad back to its default... set the homePad to "home"; -- -- The next example loads a different home pad containing some -- special routines, then re-loads the original home pad. -- put the homePad into savedHomePad; set the homePad to "C:\HPAD22\SPECIAL.PAD"; put specialFunction() into page field 1; set the homePad to savedHomePad; Note: The value of the homePad property is lost when you exit HyperPAD or run another program. Setting the homePad property also changes the pad that you go to when you select Home from the Go menu (or press ALT+F5). To remove the home pad from the message path, set the homePad property to empty. If you specify a DOS path, HyperPAD will look only in the specified directory for the pad. If you don't specify a path, HyperPAD will search for the specified pad in the following manner: o Append the PAD file extension (if there is no supplied file extension) o Search the current directory o Search the directory specified by the HPADNET environment variable o Search the directory where HPAD.EXE is located o Search every directory specified in the DOS path o Search the B: drive (if HyperPAD was started from a low density disk (360K) in A:) 44 HyperPAD 2.2 Addendum keyClick This global property, when true, causes an audible click when a key is pressed. The possible values are true or false; the default is false. Examples: set the keyClick to true; set the keyClick to false; Note: The key click is frequency 200 for a duration of 2 milliseconds. If there is a play statement executing in the background, the key click will take priority. When the click is finished, the play statement will resume execution. The key click will only occur when a key is pressed. Autorepeat keys will not generate audible clicks. mouseAhead The mouseAhead property controls the ability to press the mouse button while HyperPAD is busy. If mouseAhead is true (the default), then mouse button presses are remembered by HyperPAD in the event queue. If mouseAhead is false, then mouse button presses are discarded from the event queue when you change pages or go to another pad. This property is especially useful if you have a button that takes a long time to process. When the user presses this button and doesn't receive immediate feedback, the user may be likely to press on the button again. However, if the page changes, the mouse button press will be processed by an unknown object on the new page. You can prevent this by setting the mouseAhead property to false. Examples: set the mouseAhead to false; set the mouseAhead to true; Note: The mouseAhead setting is recorded in the HPAD.INI file. This means that the setting is remembered even after you have exited HyperPAD. HyperPAD 2.2 Addendum 45 wordWrap The new field property wordWrap allows you to specify where lines break in opaque, transparent, and scrolling fields. When wordWrap is true (the default), lines will break on the nearest word and at each carriage-return. When wordWrap is false, lines will break on carriage-returns only. Fields with the style listbox will only break lines on carriage- returns. Examples: set the wordWrap of page field 1 to false; set the wordWrap of page field 1 to true; New or Enhanced Messages idle In version 2.0, idle was sent to the current page each time through the main event loop. In version 2.2, idle is sent only when another event is not waiting in the event queue. This will affect pads that assume that idle gets sent at the end of all pending handlers. mark and unMark The mark and unMark messages can now be sent to listbox fields in order to mark or unMark a series of lines. Examples: send "mark" 1,2,5,6 to page field 1; send "unMark" 3,5,6 to page field "list"; 46 HyperPAD 2.2 Addendum New or Enhanced Commands ask The ask command has been enhanced with the keyword "password", as shown in the following example: ask password "What is the password, hombre?"; This command will allow the user to type normally using backspace and other editing keys, except that keyPress pound signs (#) will be echoed in place of printable characters. The user's response (what was actually typed -- not the pound signs) is returned in the variable "it". convert The convert command has been changed to allow 4 digit years. Thus, in the short date format has been extended to allow the following: Command Format Example convert it to short MM/DD/YY 1/31/91 date; convert it to short4 MM/DD/YYYY 1/31/1991 date; To convert a date to the format containing 4 digit years, use the "short4 date" date type as in the following example: get the seconds; convert it to short4 date; The date() function still returns dates in the short format (2 digit years), such as 10/21/90. When converting from short dates with 2 digit years, HyperPAD assumes the current century. For example, "10/10/00" will translate to 1900 because the current century is 1900. HyperPAD 2.2 Addendum 47 To get a complete date specification in short format with 4 digit years: -- old way get the date; -- new way get the seconds convert it to short4 date; dial The dial command now supports COM3 and COM4. To use these additional serial ports, use the following commands: set the modem to "COM3"; set the modem to "COM4"; dial "315-4743400"; get the modem; if it is "COM3" then answer "You have many serial ports!"; do The result of the do command can be determined by examining the result() function. This function returns error if there was a syntax error compiling the statement or empty if there was no error. Examples: ask "Type in a statement:"; do it; if the result is "error" then answer "There was an error compiling that statement."; fxshow HyperPAD now supports the no-credits version of the Show Partner F/X runtime called FXNOSHOW.EXE (version 3.6 or above). This program will only display mastered shows having the .PR2 file extension. In order to use FXNOSHOW, put the program into the same directory as HPAD.EXE and run HyperPAD. HyperPAD will search 48 HyperPAD 2.2 Addendum for the program name and check a signature. To use the program from within HyperPAD use the "fxshow" command as follows: fxshow "sample.pr2"; If both FXSHOW.EXE and FXNOSHOW.EXE are in the HyperPAD directory, HyperPAD will use FXSHOW.EXE. You will receive no credits if you are using FXNOSHOW.EXE. Command Line Parameters The fxshow command accepts optional parameters. For example, to disable the use of EMS memory in FXSHOW, use the following command: fxshow "sample.pro /n"; The /k parameter causes FXSHOW to return the last key pressed in the function result(). This is useful if you want to display a show and evaluate the last key that was pressed during the show from within HyperPAD. The following example displays the show called "sample.pro" and saves the last key that was pressed : fxshow "sample.pro /k"; To evaluate the last key, create a resume handler in the page script. For example: handler resume; begin if the result() is 27 then quit; end; In this case, the result() function returns the ASCII code of the last key that the user pressed while in FXSHOW.EXE. If the last key pressed is a special key (i.e., a function key or a key on the numeric keypad), the result() function will return the scan code of that key plus 128. Thus, if the result is greater than 128, subtract 128 and examine the resulting scan code. HyperPAD 2.2 Addendum 49 For example, the following resume handler evaluates the last key pressed in FXSHOW.EXE: handler resume; begin get the result; if it > 128 then begin subtract 128 from it; -- get the scan code if it is 59 then answer "The last key pressed was F1" else if it is 72 then answer "The last key was up arrow"; end; end; go When using the PADtalk command: go to pad <padName>; If <padName> doesn't contain a path specification, HyperPAD will search in a number of different directories until the desired pad is located. Beginning with version 2.2, HyperPAD will first search for the pad in the same directory as the current pad. If the pad is not located within the same directory as the current pad, the remaining directories (detailed on page 135 of the PADtalk Reference Guide) are searched as normal. query After a query, the following statements can be used to navigate between the pages included in the query subset: -- go to the first page in the subset go to the first page; -- go to the last page in the subset go to the last page; -- go to the next page in the subset doMenu "Next"; -- go to the previous page in the subset doMenu "Previous"; 50 HyperPAD 2.2 Addendum The following statements change to physical pages, regardless of whether the page is included in the query subset: go to the next page; go to the previous page; go to page 1; go to page 10; send The send command now changes the target to the destination object. When a message is explicitly sent to another object, the target is temporarily changed to that object. When the destination object finishes execution, the target is restored to its original value. Examples: This handler appears in page button is 1: handler select; begin put the target; send "select" to page button id 2; put the target; end; The following handler appears in page button id 2: handler select; begin put the target; end; After selecting page button id 1 (and running its select handler), the message box will display the following in this order: page button id 1 page button id 2 page button id 1 HyperPAD 2.2 Addendum 51 sort The sort command has a limitation not discussed in the PADtalk Reference Guide, namely that field references cannot contain page or background specifications. For example, the following is allowed: sort by field 1; The following, however, is not allowed: sort by field 1 of page 2; If you want to sort using a background field on a different background, you can use the following code: go to page 1 of background 1; sort by field 1; If you attempt to include a page or background reference, you will receive syntax error 16: "Page or background specification is not allowed in a sort expression.". New or Enhanced Functions dirExists() This function returns true if a specified directory is a valid; otherwise it returns false. The directory can be on the same drive or another drive. Examples: if dirExists("C:\123\SHEETS") then beep; if not dirExists(page field "dirName") then go home; -- ask for a directory, then change to it if it exists ask "What directory to change to?" with directory(); if it is empty then exit; if dirExists(it) then set the currentDirectory to it else answer "Invalid directory!" with "Ok"; 52 HyperPAD 2.2 Addendum extensions() This function returns a comma-separated list of the names of external handlers and functions that are currently loaded. Extensions in both the current pad and the home pad are returned. Examples: put the extensions into page field 1; if "blinkon" is in extensions() then blinkon; put the extensions into page field "list"; history() This function returns a comma-separated list of the unique names of the most recently accessed pages. Up to 100 page names may be returned. For example, the following list may be returned: page id 4 of pad "C:\HPAD\HOME.PAD",page id 16 of pad "C:\HPAD\PHONE.PAD",page id 3 of pad "C:\HPAD\RUN.PAD"; Examples: put the history into page field 1; -- create a history list (separated by CRs)... put substitute(history(),",",return) into page field "List"; -- go to the first page visited... get item 1 of history(); go to page id (word 3 of it) of pad (word 6 of it); The following example displays the history in a listbox field called "PreviousPages": get the history; get substitute(it,",",return); put it into page field "PreviousPages"; HyperPAD 2.2 Addendum 53 open(), append(), and create() HyperPAD now limits the number of open files to 10. If you attempt to open more than ten files (using open(), create() or append()), you will receive the runtime error message number 59: "Too many open files.". With version 2.2 of HyperPAD, the numbers returned from open(), create(), and append() are the same as the corresponding DOS file handle numbers. Thus, you can reference the open DOS files from extensions. Examples: put the open of "data.dat" into fh; close fh; put the create of "newfile.txt" into fh; write page field 1 to fh; close fh; programName This function returns the name of the HyperPAD program that is currently running. The possible return values are: Possible Value Description HyperPAD Standard HyperPAD development environment HyperPAD Runtime version of HyperPAD Browser HyperPAD Easy OEM version of HyperPAD HyperPAD Old runtime version of HyperPAD Reader with menus HyperHost HyperPAD development environment with host connectivity software HyperHost Runtime version of HyperHost Browser 54 HyperPAD 2.2 Addendum printLoc() This function returns the internal printhead position (used with the print at command) in the format X,Y. When printing using the print at command, HyperPAD internally keeps track of the X and Y character positions on the print head on the page. This is done in order to move the printhead to different locations on the page using the syntax: print "hello world" at 10,10; The printLoc() function returns undefined values if the printer is not currently on. (You can turn the printer on and off using the global property: printer.) The following sequence shows how different statements affect the internal printhead position: put the printLoc(); -- undefined X,Y values (printer -- is not on!) set the printer to on; put the printLoc(); -- puts 1,1 into the message box -- (default starting position) print "Hello"; put the printLoc(); -- puts 6,1 into the message box print return & return; put the printLoc(); -- puts 1,3 into the message box print "Hello" at 10,10; put the printLoc(); -- puts 15,10 into the message box print formfeed; put the printLoc(); -- puts 1,1 into the message box -- (resets to top of page) set the printer to off; put the printLoc(); -- undefined X,Y values Examples: if item 2 of the printLoc >= 66 then print formfeed; HyperPAD 2.2 Addendum 55 if item 1 of printLoc() > 80 then print return; random() The upper limit of random numbers generated by HyperPAD has been changed to 4294967296 (or 2^32). Further, the random function will also work with negative numbers, returning a value between - 1 and the lower bound you specify. Examples: put random(1000); -- returns a number between 1 and 1000 put random(-1000);-- returns a number between -1 and -1000 put random(4000000); -- get a big random number put the random of (4123456) into the message box; ticks() The ticks() function returns the number of millisecond (1/1000) ticks since HyperPAD was run. In HyperPAD 2.2, this number is accurate to 1/18 of a second (instead of 1/1000) of a second. get the ticks; for i = 1 to 10 do go to the next page; answer "That took" && ticks() - it && "milliseconds"; When timing different events, remember that the HyperPAD instructions take time to execute too. Enhanced Objects currentObject object The currentObject object can now be used as an object reference while using the Selector tool. 56 HyperPAD 2.2 Addendum Extension Enhancements New Extension Callbacks The following list describes the new callback functions available to extensions. Routine Description GetGlobals Returns a comma-separated list of global variables GetScreen Retrieves the character and attribute information from a rectangular area of the paint layer of the current page or background SetKeyHook Installs a keyboard intercept routine SetScreen Sets character and attribute information of a rectangle of the paint layer of the current page or background TranslateKey Translated a key name to a numeric value To use these new callback functions, you must use the following new files: o STARTUP.LIB o EXTERN.H o EXTERN.INC o KEYCODES.H GetGlobals() Syntax: hNames = GetGlobals(); HANDLE hNames; Purpose: This returns a comma separated list of all the global variable names. When used with SetGlobal() and GetGlobal(), an extension could, for example: HyperPAD 2.2 Addendum 57 o Put empty into all of the global variables in HPAD o Save all the global variables to a file o Read global variable names and values from a file and set them in HPAD If there are three global variables in HyperPAD called i, j, and k, then GetGlobals() will return "i,j,k". Examples: // This code prints out the names and contents // of all the global variables currently declared // in HyperPAD. HANDLE hGlobals; HANDLE hName; HANDLE hValue; PTR s,d; hGlobals = GetGlobals(); // get the global variable names hName = NewHandle(50); // temporary space to hold single names s = LockHandle(hGlobals); // s = pointer to the names while (TRUE) { // copy a global variable name to hName d = deref(hName); while (*d && *d != ',') *d++ = *s++; *d = '\0'; // get the variable's value hValue = GetGlobal(hName); // print them out printf("Global %s = %s\n",deref(hName),deref(hValue)); // next global variable if (*s) s++; else break; } //cleanup UnLockHandle(hGlobals); FreeHandle(hName); 58 HyperPAD 2.2 Addendum GetScreen() Syntax: hdl = GetScreen(IsPage,x1,y1,x2,y2); HANDLE hdl; /* handle to the screen data */ BOOLEAN IsPage; /* TRUE = page, FALSE = background */ int x1,y1,x2,y2; /* screen rectangle coordinates */ Purpose: This function returns the screen data from a specified rectangle from the paint layer of either the current page or current background. The function returns the character and attribute data within the rectangle specified by the upper left corner of (x1,y1) and the lower right corner of (x2,y2). The screen data is of the form: <character>,<attribute>,<character>,<attribute>.... The size (in bytes) of the returned handle can be calculated as follows: (x2-x1+1)*2 + (y2-y1+1) The returned data is of a form suitable for use with SetScreen(). Note: This function allocates a handle. It is the responsibility of the extension to free this handle. HyperPAD 2.2 Addendum 59 Examples: /* ** this code copies the paint layer from the current ** page to the next page. */ HANDLE hdl; HANDLE hcmd; /* get the screen data */ hdl = GetScreen(TRUE,1,1,80,25); /* issue command to HyperPAD to go to the next page */ hcmd = stoh("go to the next page"); Do(hcmd); FreeHandle(hcmd); /* set the paint layer of the new page */ SetScreen(TRUE,1,1,80,25,deref(hdl)); /* free the screen data (no longer needed) */ FreeHandle(hdl); SetKeyHook() Syntax: SetKeyHook(trap); WORD _loadds (*trap)(WORD); Purpose: This routine enables an extension to insert a keyboard interceptor into HyperPAD message path. This interceptor will receive keystrokes before the key enters the hierarchy, thereby allowing the extension to provide a keyboard filter. The filter routine accepts one parameter (the key -- WORD) and returns the key to HyperPAD. If zero is returned, the key will be ignored. The interceptor must preserve and set DS to its own value. 60 HyperPAD 2.2 Addendum Examples: The following example extension uses a keyboard interceptor to filter out lower case letters, allowing only their upper case equivalents. The PADtalk code used in conjunction with this extension is provided afterward. #include <ctype.h> #include "extern.h" /* ** This keyboard hook filters all alphabetic characters, ** passing only the upper case equivalents. ** ** Keyboard hooks must save the DS register (using ** _loadds) */ WORD _loadds trap(WORD KeyWord) { WORD w; w = KeyWord & 0x00FF; /* w = ASCII code */ if (w) { if (isalpha(w)) return((KeyWord & 0xFF00) | toupper(w)); } return(KeyWord); } startHook() { SetKeyHook(trap); /* set to my routine */ return(STOP); } stopHook() { SetKeyHook(NULL); /* set to nothing removes hook */ return(STOP); } HyperPAD 2.2 Addendum 61 /* ** Remove the keyboard hook when the extension ** is removed from memory. */ pascal far WhenUnLoaded() { stopHook(); } POOL pascal Pool[] = { { "startHook", startHook, 0 HANDLER}, { "stopHook", stopHook, 0, HANDLER}, { NULL, NULL, 0, 0} }; These PADtalk handlers should appear within the script of a field that requires only upper case input: handler openField; begin startHook; end; handler closeField; begin stopHook; end; SetScreen() Syntax: SetScreen(IsPage,x1,y1,x2,y2,data); BOOLEAN IsPage; // TRUE the page, else FALSE int x1,y1,x2,y2; // rectangle to change PTR data; // place to put the data Purpose: This routine permanently changes a portion of the paint layer of the current page or background with data from a buffer that you supply. The data buffer contains both character and attribute information in the form: <character><attribute><character><attribute>... You can get data from the paint layer in this format using the GetScreen() function. 62 HyperPAD 2.2 Addendum Examples: The following example clears the 25th line of the page: char buf[160]; // 160 bytes (80 chars and 80 attrs) PTR p; // roving pointer into the buffer int i; // loop counter // initialize the buffer with blank space... for (i=0,p=buf;i<80;i++) { *p++ = ' '; // character *p++ = 7; // attribute } // copy the data to the paint layer and refresh... SetScreen(TRUE,1,25,80,25,buf); TranslateKey() Syntax: key = TranslateKey(keyName); WORD key; STRING keyName; Purpose: This function enables an extension to translate a key, represented as a string, into a number. For example: WORD w; w = TranslateKey("enter"); // returns 7181 Sample Extensions If you chose to install the sample extensions, a subdirectory called EXTERN was created off your HyperPAD directory. This directory contains a number of sample extensions that you can use within your own pads. Included with each extension are the following: o The compiled form of the extension suitable for use with the MOVER program (Example: TEST.EXE). o The make file used to compile and link the extension. These files have no file extension (example: TEST.). HyperPAD 2.2 Addendum 63 o A pad showing how to use the handlers and function provided in that extension (example: TEST.PAD). Not all extensions have a sample pad. o The source files needed to create that extension (example: TEST.C or TEST.ASM). Each extension was created using Microsoft C 5.1 or Microsoft Macro Assembler version 5.0. Within the EXTERN directory are two sub-directories: STARTUP and IO. The STARTUP directory contains the source code for the startup library (STARTUP.LIB) that is linked with every extension. Use care if you modify this code. The IO directory contains the source for the I/O library (IO.LIB) that is also used in many extensions. If you do not need the source code for these two libraries, then you can delete the files and remove the corresponding subdirectories. 64 HyperPAD 2.2 Addendum The following table describes the new extensions included with version 2.2: Extension Description BARCHART Graphs data as a bar chart (640x200 BW graphics mode). BASE Converts numbers to and from other bases (such as hex or binary). BLINK Toggles blinking attributes on/off. BOOT Reboots the computer (from a read- only pad). BORDER Sets the border color on the display. CLEARBUF Clears the event queue of all keyboard and mouse events. CLICKAT Simulates a mouse click anywhere on the screen. CSORT Sorts items or lines of text. DOS DOS functions, such as md, rd, copy, and del. FF Locates a file anywhere on a disk. FIXENV Causes HyperPAD to use the environment of COMMAND.COM rather than the copy created for it by DOS. This is useful for running some network programs. FONT Changes the text font on EGA or VGA cards. FORMAT Word wraps a text string for display in a field. GETSCR Copies and pastes the paint layer of the page or background. GLOBALS Saves and reads global variables to and from a file. HORLINE Draws a horizontal line of characters and attributes on the paint layer of the page or background. INFO Returns information about the computer and memory configuration. ISSUBST Determines if a drive is a DOS SUBST drive. HyperPAD 2.2 Addendum 65 KEEP Causes HyperPAD not to clear the screen when running other programs. KEYHOOK Shows how to intercept keys before they enter the HyperPAD message path. LOWIO Low level DOS I/O functions. MONTH Creates a calendar month for display in a field. NUMBER Creates enlarged numeric digits for display in a field. SCAN Reads in a directory tree of a specified disk drive and returns the structure formatted as text for display in a field. SETPAL Modifies the palette registers and DAC values of the EGA and VGA. SETSCR Shows how to set the paint layer of a page or background. SWITCH Switches between monitors -- used with computers with both monochrome and color monitors. TEST Sample C extension showing a handler and a function. TESTASM Sample ASM extension. TSR A sample of a TSR program that registers itself with HyperPAD and executes some HyperPAD callback functions when invoked. VIEWGX2 Views a graphics GX2 file. WITEM Returns the item number, given the item's value. 66 HyperPAD 2.2 Addendum Support for TSR Programs HyperPAD now has additional support for TSR programs. This support allows TSR programs to: o Invoke themselves in a safe manner that will not conflict with HyperPAD. o Make calls into HyperPAD via the extension callback mechanism. Using this mechanism, TSR programs can be invoked in the following manner: 1. The TSR is invoked (possible via a key sequence). 2. The TSR checks to see if HyperPAD is installed. If so, the TSR registers itself with HyperPAD, passing HyperPAD the address of a routine to call when it is ready. 3. After registering, the TSR shuts down. 4. HyperPAD will call the TSR via this communicated address after all pending handlers have stopped execution (during the next idle message). The called procedure should follow the C calling conventions, preserving DS, but using HyperPAD's stack. Calling the TSR in this way insures a safe environment for the TSR. Further, the TSR program can use the callback mechanism available in HyperPAD to perform such tasks such as: o Showing/hiding the mouse o Make windows o Allocate/deallocate memory o Send messages to the current page o Change the paint layer of the current page and background o Access and change global variables o Access and change the contents of page or background fields HyperPAD 2.2 Addendum 67 International Support Date Separator HyperPAD now uses the correct date separator corresponding to the country information reported by DOS. This affects the following: o The function date() now returns the date with the correct date separator. o The convert command will use the correct separator if the input date has no separator. Otherwise, the input date separator character will be used in the target date string. Short Date Format The short date format is now returned using the country information returned by DOS. The following date formats are supported: m-d-y USA d-m-y Europe y-m-d Japan This affects the following: o The function date() o The convert function when converting to and from the short date format 68 HyperPAD 2.2 Addendum International support in longFiles() function The longFiles() function now supports international date formats and date separator. Storing dates in your pads Because HyperPAD uses short date formats specific to the country reported by DOS, it is necessary to store dates in the seconds format in your pads and then convert them to the correct format for display. Thus, the ordering of the month, day, and year, and the date separator characters will be determined at runtime. HyperPAD 2.2 Addendum 69 Miscellaneous Enhancements Support for Three button mice HyperPAD now supports three button mice. The mouseButton() function returns 4 if the middle button is currently pressed. Further, the middle button generates a mouseDown message. Overlay errors If HyperPAD is unable to load an overlay (either HPAD.OVL or HPAD22.OVL), the following error message will be displayed: Overlay error XX. Unable to load FILENAME.EXT. where XX is the overlay error number and FILENAME.EXT is the name of the overlay file that couldn't be loaded. The different overlay errors are: 0 The user cancelled the "Where Is" dialog box when HyperPAD couldn't find the overlay file 1 Overlay file was not found 2 Overlay file couldn't be opened due to disk error (such as no disk in drive, drive not ready, or media errors) 3 Overlay file couldn't be read properly -- the .OVL file is smashed. 4 Overlay file couldn't be read due to disk error 5 Invalid file handle was returned by DOS When HyperPAD looks for an overlay for the first time, it performs the following tasks: 1.Search the current directory. 2.Search the directory specified by the HPADNET environment variable, if this defined. 3.Search the directory where HyperPAD was started. 4.Search the directory containing HPAD.EXE. 5.Search every directory specified in the DOS path. 70 HyperPAD 2.2 Addendum 6.Search on drive B:, if HyperPAD was started from low density (360K) A:. 7.If still unable to locate the overlay, HyperPAD will ask you where the overlay is located using the "Where Is" dialog box. This gives you a chance to specify exactly where the overlay is located. If you cancel this dialog box, you will receive error 0, listed above. When you exit HyperPAD, the directory containing the overlays is saved in the HPAD.INI file. Thus, the next time you load HyperPAD, no searches will have to be performed to find HyperPAD's overlays. However, be careful that you don't mix versions of HyperPAD, because an old INI file contains the path of the OLD overlay files, and if HyperPAD attempts to read in old overlay files, the computer will hang. Utility Enhancements PADINFO.EXE The PADINFO utility program now accepts a pad specification on the command line. For example: padinfo *.pad padinfo c:\pad\*.pad padinfo c:\pad\j*.pad padinfo home padinfo * PADINFO can be used to determine the version of HyperPAD that created the pad -- pads created by HyperPAD 2.2 return 7 as their version number. HyperPAD 2.2 Addendum 71